PutScrap

PutScrap
Header:	Scrap.h		Carbon status:	Unsupported

Writes data to the current location of the scrap.

OSStatus PutScrap (
    SInt32 length, 
    ResType theType, 
    const void *source
);

length: The amount (in bytes) of data to write to the scrap.
theType: The scrap format type of the data you wish to write to the scrap. The scrap format type is a four-character sequence that refers to the particular data format, such as 'TEXT', 'PICT', 'styl', 'snd ', or 'movv'.
source: A pointer to the data that the function should write to the scrap.

function result: A result code. Returns noScrapErr if the scrap at source does not already exist (in memory or on the disk).

DISCUSSION

If your application uses a private scrap, it should copy data from its private scrap to the scrap using this function whenever it receives a suspend event.

Your application can use this function multiple times to write different formats of the same data to the scrap. Whenever your application needs to write data in one or more formats to the scrap, you should call the ZeroScrap function before the first time you call this function. If your application writes multiple formats to the scrap, you should write your application’s preferred scrap format type first. For example, if the SurfWriter application’s preferred scrap format type is a private scrap format type called 'SURF' and SurfWriter also supports the scrap format types 'TEXT' and 'PICT', then SurfWriter should write the data to the scrap using the 'SURF' scrap format type first, and then write any other scrap format types that it supports in subsequent order of preference.

Do not write data to the scrap that has the same scrap format type as any data already in the scrap. If you do so, the new data is appended to the scrap. Note that when you request data from the scrap using the GetScrap function, GetScrap returns the first data that it finds with the requested scrap format type; thus you cannot retrieve any appended data of the same format type using GetScrap.

If your application uses TextEdit to handle text in its documents, use TextEdit functions to implement cut and copy operations and to write the TextEdit scrap to the scrap. If your application uses the Dialog Manager to handle editable text in your application’s dialog boxes and a dialog box is the frontmost window, use the Dialog Manager function DialogCut or DialogCopy to copy the data from the current editable text item to the scrap.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Not supported in Carbon. Not available in CarbonLib, but available when InterfaceLib 7.1 or later is installed. Exported by InterfaceLib 7.1 and later.

CARBON NOTES

You should instead use the function PutScrapFlavor.